Languguage OS 2

home *** CD-ROM | disk | FTP | other *** search

/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / pcpil / pidoc1.txt < prev next >

Wrap

Text File | 1994-03-01 | 39KB | 966 lines

PC/PILOT LANGUAGE REFERENCE MANUAL - Version 3.0 Notice: On your PC/PILOT diskette is a text file named README, with additional documentation you need. Use the DOS command TYPE README to display it. Washington Computer Services, Bellingham, Washington, U.S.A. COPYRIGHT NOTICE This manual and the PC/PILOT program COPYRIGHT 1985-1994 Larry Kheriaty DISCLAIMER NOTICE No warrantees are made with respect to the adequacy of the software for any particular purpose. Contents Chapter 1. Using PILOT Learning the PILOT Language . . . 1-1 How to Install PILOT . . . 1-1 System Requirements . . . 1-2 Sample Programs . . . 1-2 How to Write a Program . . . 1-2 How to Print a Program . . . 1-3 How to Run a Program . . . 1-3 PILOT Program Sizes . . . 1-4 Chapter 2. PILOT Statements PILOT Statements . . . 2-1 Statement Labels . . . 2-2 Modifiers . . . 2-3 Conditionals . . . 2-4 Accept . . . 2-6 Compute . . . 2-12 Dimension . . . 2-17 End . . . 2-20 File . . . 2-21 Graphics . . . 2-28 Jump . . . 2-37 Keep Records . . . 2-41 Link . . . 2-42 Match . . . .2-43 New Character . . . 2-48 New Height . . . 2-50 New Font . . . 2-51 New Key . . . 2-55 Problem . . . 2-56 Poke, Out . . . 2-59 Remark . . . 2-60 Sound . . . 2-61 Type . . . 2-62 Type Screen . . . 2-67 Use . . . 2-77 Video . . . 2-78 Wait . . . 2-80 Execute Indirect . . . 2-81 Chapter 3. Operators and Expressions Data Types . . . 3-1 Variables . . . 3-2 Subscripting . . . 3-3 Numeric Constants . . . 3-6 String Constants . . . 3-7 Operators . . . 3-8 Functions . . . 3-9 Chapter 4. GOTO and Escape Commands GOTO Command . . . 4-1 Escape Command . . . 4-1 Chapter 5. Error Messages . . . 5-1 Chapter 6. Distributing Programs . . . 6-1 Chapter 7. EZ Editor EZ Function Keys . . . 7-1 Using the Pick Stack in EZ . . . 7-3 Search and Replace . . . 7-4 Macros in EZ . . . 7-4 Extended Characters in EZ . . . 7-5 Character Editor . . . 7-6 Select Mode . . . 7-8 Grid Mode . . . 7-8 How to Write a Macro for EZ . . . 7-10 Chapter 8. Sprites Sprites . . . 8-1 How to Create and Edit Sprite Tables . . . 8-4 Using Sprites in a PILOT Program . . . 8-11 Sprite Commands . . . 8-13 Sprite Examples . . . 8-16 Chapter 9. PILOT Tutorial . . . 9-1 Chapter 10. Font Editor Using the Font Editor . . . 10-2 Main Menu . . . 10-2 Select Mode . . . 10-3 Fat-Bits Mode . . . 10-5 Changing Global Parameters . . . 10-10 Appendix A: PILOT Language Summary . . . A-1 Appendix B: PILOT Character Set . . . B-1 Appendix C: Student Records . . . C-1 Chapter 1. USING PILOT This chapter explains how to install and operate PILOT. LEARNING THE PILOT LANGUAGE For the person unfamiliar with programming, a beginner's tutorial is found in chapter 10 of this manual. For the person already familiar with programming chapter 2 describes the various statements of the language. Appendix C lists various other resources that may be helpful in learning and using PILOT effectively. Regardless of your particular level of expertise, the first step to take is to install PILOT according to the instructions found below. HOW TO INSTALL PILOT PILOT requires no special installation. All you need to do is make a working copy of the PILOT distribution diskette, then store the original in a safe place. You can make a working diskette by following these steps: 1. Boot DOS, if not already running 2. Place a blank diskette in drive B: 3. Enter the command FORMAT B: 4. Place the PILOT diskette in drive A: 5. Enter the command COPY *.* B: If you have a fixed disk you should create a directory called \PILOT,then copy all files from the PILOT diskette to that directory. When working with PILOT place a working copy of the diskette in the current default disk drive. (On a fixed disk, change to the \PILOT directory.) If you need more space on your working diskette, you can remove all the sample programs by the command ERASE SAMPLE*.PIL . SYSTEM REQUIREMENTS PILOT works best if you have at least 256K bytes of memory. Although PILOT will run on a 128K system, program size and the use of some memory-intensive features will be restricted. Although PILOT operates on either a monochrome or color video adapter, many of PILOT's graphics features are available only on a color video adapter. SAMPLE PROGRAMS Several sample programs are provided on your PILOT diskette. Each one has a file name of the form SAMPLEn.PIL. n represents a number. You can run a sample program by entering: PI SAMPLEn Some of the samples are very simple. Others demonstrate fairly advanced programming techniques. Run each program and observe the results. Then examine the program file to see how the program was written and to obtain examples of various types of statement sequences. Particularly useful is SAMPLE1.PIL. It allows you to enter PILOT statements one at a time. Each statement is executed immediately as it is entered. This can help you to try out various PILOT features quickly without writing a program. HOW TO WRITE A PROGRAM A PILOT program is a text file which contains a series of PILOT STATEMENTS. Programs are written using a text editor to create the text file and stored on disk under a name of your choosing. Included with PILOT is the EZ editor. It is designed to be simple to use while providing several special features to aid in PILOT programming. The EZ editor is described in a later section of this document. Since PILOT programs are text files, you can use any other text editors or word processors that operate on DOS text files. When you write a PILOT program, you must give it a name of the form name.PIL, where name is any word you choose. .PIL is called the file type and identifies the file as a PILOT program. HOW TO PRINT A PROGRAM To list the names of all PILOT programs in the current disk and directory use the DOS command: DIR *.PIL To list a program on the screen use the DOS command: TYPE name.PIL To print the listing on your printer, first ready the printer, then enter the command: COPY name.PIL PRN: HOW TO RUN A PROGRAM To begin execution of a PILOT program enter: PI name where name.PIL is the path name of the file which contains the PILOT program to be run. The suffix of ".PIL" is appended automatically by PILOT. You should not type it when entering the file name. Per normal DOS conventions, you can precede the PI by an optional drive designation if the file PI.EXE is not in the current disk drive. The file name can be a full DOS path name if the file is not in the current disk or directory. Thus the program to be run can be in any directory, any drive, and any network node desired. When a program ends, control is returned to DOS. A program may be prematurely canceled at any time by pushing ctrl C (ie, push the C while holding down the ctrl key). PILOT PROGRAM SIZES When PILOT starts, a program buffer is set aside from the available memory. Unless the PI command line indicates otherwise, the buffer size is 32K bytes. You can specify another program buffer size by adding a parameter to the PI command line as follows: PI name n where "n" can be a number from 1 through 8. The program buffer size is set to n*8K bytes. A maximum value of 8 indicates a program buffer size of 64K bytes. If the requested amount of memory is unavailable, then a program buffer of 8K bytes is allocated from PILOT's internal string space. Chapter 2. PILOT STATEMENTS A statement follows the following general format: *label op-code <modifiers/conditionals> : arguments The *label is optional. The modifiers may be coded in any order. If a particular modifier does not make sense for the op-code, the modifier is ignored. The op-code represents the type of statement to be executed. The op-code, modifiers and conditionals may be upper or lower case. There may be no spaces within the op-code, modifiers or conditionals (except within conditional expressions). There must be a colon after the op-code modifiers and conditionals. After the colon there may be further arguments. The format and meaning of the arguments after the colon depend on the particular op-code. A PILOT program is a sequence of statements. Each statement is written on one line. The maximum statement length is 256 characters. A program may consist of any number of statements, limited only by the amount of disk space available. Programs may be created using any editor which produces standard ascii formatted text files. It is recommended that you use the EZ editor provided with PILOT to create your program files. EXAMPLE 1: A simple Type statement. T:Welcome to Biology 301. See also: STATEMENT LABELS, MODIFIERS, CONDITIONALS STATEMENT LABELS A statement label is preceded by a "*" character and consists of one to six alphanumeric characters (letters and digits). A label may be alone on a line or may precede a statement on the same line. Upper and lower case letters are considered equivalent within labels. A label serves the purpose of providing a branch point (place to jump to). Unless instructed otherwise, PILOT runs a program by executing successive statements in the order that they occur in the program. Using the Jump (J) statement provides a means of altering the natural program flow by jumping from one location within the program to another location, marked by a label. For efficiency, PILOT automatically optimizes label addressing for labels that are at least two characters long. For this reason, it is recommended that one-characters labels not be used when execution speed is important. EXAMPLE 1: Label as a target for a Jump; label written on same line as statement. T:We will now proceed directly to part3. J:PART3 . . . . . . *PART3 T: The next question is... EXAMPLE 2: Label written alone on a line. *REVIEW T:Let us look again at the diagram... See also: JUMP MODIFIERS A modifier is a letter appended to an op-code. It causes change in the way the statement is executed. The letters used as modifiers are H, J, S and X. The specific meaning that a modifier takes on depends entirely on the op-code to which it is appended. The modifier letters are used to designate variations on the operation of the basic statement types. For example, the "S" modifier, when appended to the M: op code gives the "match-spelling" statement. In this case the "S" modifier is sometimes referred to as the "spelling" modifier. The same letter, S, when appended to the A: op code yields the "accept single" statement. It modifies the normal operation of the accept statement to input an answer of only one key rather than the normal one line. If a modifier (H, J, S or X) is appended to any op-code for which the meaning is not yet defined, the modifier has no effect on the statement. CONDITIONALS A conditional is a letter, digit or expression appended to any op-code. The conditional causes the statement to be executed only if the condition is true. If it is false, then the statement is skipped. Each conditional is shown below as appended to a TYPE statement, however, each can be appended to any type of statement. TY: - type if last match was YES TN: - type if last match was NO TE: - type if error flag is true T(exp): - type if expression is true The expression is evaluated, if it is true (non zero) then the statement is executed, otherwise it is skipped. TC: - type if previous expression was true Tn: - type if accept counter=n n may be a number from l to 9. Type if n is equal to the accept counter. The accept counter is a value which tells how many times the last accept has been executed in a row. Any number of conditionals may be appended to the op-code. All must be true for the statement to be executed. If any conditional is found to be false, the remainder of the statement is skipped over, and execution continues with the next statement in line. EXAMPLE 1: Y and N conditions to test a student response for correct or incorrect. T:How many feet in a yard? A: M:three TY:Correct TN:Incorrect EXAMPLE 2: Conditional expression and C condition to re-test same condition. T(TRY < LIMIT): No, look at this. JC: REVIEW EXAMPLE 3: Conditional expression used to create a loop to print digits 1 through 9. C: I=1 *LOOP TH:#I, C:I=I+1 J(I<10):LOOP EXAMPLE 4: N and digit condition used in combination to give successive hints. T:What do we call an 8 sided figure? A: M:octagon TY:Right TN1:Hint: A STOP sign is one. TN2:Hint: An octopus has eight arms. TN3:That's your third wrong try. EXAMPLE 5: E condition used as a check for a numeric answer. T:What is 4+5? A: #N TE:Please type a number. JE:@A M:9 TY:Right. See also: MATCH, ACCEPT ACCEPT - input student response A: A: $variable$ #variable AH: AJ: AS: AX: ACCEPT is used to input a student response. When the ACCEPT is encountered, PILOT waits for the student to enter an answer. The student types a response followed by the Enter key. While typing the response, the student can use the Backspace key to correct typing errors. The response is automatically edited per the space and case options last set on a PROBLEM statement. These options can be used to convert answers to all upper or all lower case, or to remove spaces from the answer. The edited response is then placed in the system variable %B, also called the answer buffer. Characters typed by the student are displayed on the screen. When the student pushes the Enter key to end the response, the cursor is moved to the start of the next line. However, if the H (hang) modifier is added to the ACCEPT statement then the cursor is left hanging at the end of the student response. ANSWER LENGTH LIMIT Unless otherwise specified, the student answer is limited to a maximum of 80 characters. The An option of the PROBLEM statement can be used to set the answer length limit to any value from 1 to 256 characters. The answer length limit can not be set to a value greater than 256 characters. ACCEPT SINGLE The S (single) modifier appended to the ACCEPT (AS:) limits the response to one keystroke regardless of the current response length limit. When the S modifier is appended to the ACCEPT, no editing of the value is done; it is placed in the answer buffer as a one character string. USE OF KEYBOARD TYPE-AHEAD Unless the program indicates otherwise, the student can not type the answer prior to the program reaching the ACCEPT statement. The J modifier (AJ:) allows type-ahead to be used for this ACCEPT. With type-ahead enabled, keys pushed prior to the ACCEPT statement "count" as part of the reply. INPUT OF SPECIAL CHARACTERS Input characters in the range of ascii 32 to 255 are accepted as input data. The normal Ascii character set consists of characters from 32 to 127. The characters in the range 128 to 255 are used for the text mode extended character set, and for user-defined characters. Appendix A contains a complete list of the standard codes generated by each keyboard combination. The NX: statement can be used to change the code generated by any particular keyboard key or combination. If the X modifier is not appended to the ACCEPT op-code, then the values input for each key on the keyboard are affected by previous NX: statements. If the X modifier is appended to the ACCEPT (AX:), then all keys generate their default standard values regardless of any previous NX: statements. STUDENT RESPONSE TIMING Unless otherwise specified, the student can take any duration of time to respond. However, a time limit can be set by the Tn option of the P: statement. If the student has not pushed the Enter key within the time limit, then PILOT proceeds as if the Enter key had been pushed. Whether there is a time limit or not, the built-in function TIM(0) returns the length of time (in seconds and fractions of a second) taken by the student to respond to the last ACCEPT. SETTING VARIABLES One or more string or numeric variables may be placed after the colon on an ACCEPT. Each variable name must be preceded by a $ or a #. For each string variable, the value of the answer buffer is assigned to the string. For each numeric variable, the first number found in the answer buffer is assigned to the variable. If more than one numeric variable is written, each variable is set to the same value. If a numeric variable is included on the ACCEPT statement, and no number is found in the student answer, the E condition is set to true. By checking the E condition after the ACCEPT statement, it is possible to determine whether a numeric reply was given. THE GOTO COMMAND If the G option has been enabled on a previous PROBLEM statement, the student can enter a GOTO command rather than an answer. To do so, the student must type: GOTO label The label typed by the student must correspond to a label within the program. Naturally, this is of use to the student only if the student has been instructed as to the possible labels to go to. Usually, the GOTO command is most useful to the program author when debugging or testing the program. It would allow the author to test various sections of the program, skipping over other sections not of interest. ESCAPE FEATURES Often it is desirable to allow the student to push certain function keys or escape keys to cause pre-defined actions to take place. These actions might be a return to a menu, review of a previous question, a help screen, a glossary, etc. In many cases you wish the student to be able to use these special keys at any time that the student is expected to reply. It would be inconvenient to place the necessary statements to do the special key checking at every answer point. So PILOT provides for automatic checking of special "hot" keys. There are two possible levels of key checking available. The E option on the PROBLEM statement indicates that the ESCAPE key and the @ key are to be trapped. The F option on the PROBLEM statement indicates that the function keys, the shifted function keys, and the cursor keypad keys are all to be trapped. The program can enable either, both or neither of these options. All special keys (except the @ key) are trapped immediately when pressed by a student responding to an ACCEPT statement. The @ key is only trapped when entered as the first character of a response, and only after the ENTER key has been pushed. (The use of the @ key is retained only for compatibility with older versions of PILOT.) When one of the special keys is detected by the ACCEPT statement, the following actions take place. 1. The key value is placed in the answer buffer, %B, after any previously typed characters. 2. The ACCEPT statement is immediately halted. 3. PILOT performs the equivalent to the line U:SYSX That is, it calls the subroutine named *SYSX in the current program. It is up to the programmer to insure that there is a label *SYSX in the program. The *SYSX routine can determine exactly which special key was pressed by: C: F = ASC(%B(LEN(%B)) which would set the variable F to the value 27 for the Escape key, or a value from 187 to 221 for one of the function or cursor keys. Appendix A contains a complete listing of the codes generated by the various keys. Note that if you wish to change the set of keys that are trapped, you can use the NX: statement to change the codes received by the various keys. When the effects of NX: statements are taken into account, any keys in the range 187 to 221 are trapped; any other keys are not. Once control is passed to the SYSX subroutine, it is up to the program to implement whatever action is to take place. At the end of the SYSX subroutine, the program could return to re-execute the ACCEPT via: E:@A The subroutine can also branch off to another location in the program by a statement such as: E:MENU3 ACCEPT EXAMPLES EXAMPLE 1: simple answer input T:What is the capital of Norway? A: EXAMPLE 2: accept numeric answer A: #X TE: I need a number. Try again. JE: @A EXAMPLE 3: accept a fill-in-the blank answer TS:G0,10 TH:Mary had a lamb. TS:G11,10 P:A7 AH: EXAMPLE 4: input any one key AS: T: The key value is #(ASC(%B)) EXAMPLE 5: input a timed response P:T5 TH: 6 x 8 = A: T:You took #(TIM(0)) seconds. See also: PROBLEM, NX:, GOTO AND ESCAPE COMPUTE - assignment statement C: target = expression C: target = expression ; target = expression ; C: target = expression \ remarks The COMPUTE statement is used to perform numerical computations, or to perform string manipulation. Any number of assignments may be made on one compute line by separating each from the previous by a semi-colon. A remark or comment may be placed after the assignments by preceding the remark with a back-slash, "\". Numerical computations consist of operations such as addition, subtraction, multiplication, and division. String manipulation consists of operations on character strings, such as capitalization, picking a word out of a sentence, or combining several words into a sentence. A COMPUTE statement always contains an = sign. On the right of the equal sign is an expression. A complete discussion of expressions may be found in a later section of this manual. However, in general, an expression is a series of numeric or string operations to be performed which result in a value. The resultant value can be a number, or it can be a character string. On the left side of the = sign is a target variable. The target may be a numeric variable, a subscripted array variable, a string variable, a subscripted string variable, or the system variables %B or %A. The COMPUTE statement evaluates the expression, then assigns, or sets, the target to the resultant value. ASSIGNMENT TO NUMERIC VARIABLE A variable that has not been explicitly made to be a string or array is called a numeric variable or a simple variable. Such a variable stores a single numeric value. If the target of the COMPUTE is a numeric variable, then the expression is expected to yield a number when evaluated. The number value is stored in the variable, replacing any previous value the variable had. If the expression happens to produce a string value rather than a numeric value, PILOT automatically converts the string value into a numeric value, then assigns the numeric value to the the variable. To convert the string value to a numeric value, PILOT takes the first number found in the string, searching from the left. If there is no number in the string, the numeric value is zero. The system variable %A, which contains a count of the number of times the current ACCEPT statement has been responded to, is considered to be a numeric variable. It can be used in an expression or can be the target of the COMPUTE. EXAMPLE 1: assignment to numeric variable C: X = 5 + 4 sets X to 9 C: X = X / 2 sets X to 4.5 C:AGE="I am 14 years old" sets AGE to 14 C: X=1 ; Y=2 ; Z=3 sets 3 variables ASSIGNMENT TO SUBSCRIPTED VARIABLE An array variable is a variable name which represents a list of numeric values. The DIMENSION statement is used to create an array variable. An individual item within an array can be identified by placing the number of the item in parentheses after the array variable name. The number in the parentheses is called a subscript. Array items are numbered from 0, for the first item in an array, to the number specified in the Dimension statement which created the array. Each item in an array can be thought of as a numeric variable. The only difference is that a variable is identified by its own unique name, whereas an array item is identified by both an array name and a subscript. Assignment to an item within an array is similar to assignment to a numeric variable. EXAMPLE 2: assignment to the items in an array D:Z(3) C:Z(0) = 100 C:Z(1) = 200 C:Z(2) = 300 C:Z(3) = 1000 ASSIGNMENT TO A STRING VARIABLE A string variable is a variable which can store a character string. A character string is a list of characters, such as "ABC", "Banana", or "The Declaration of Independence". A string variable name always ends with a "$". Also, before a string variable can store a string value, the DIMENSION statement must be used to set aside space for the string variable. When a string variable is created by the DIMENSION statement you must specify the number of characters, or bytes, to be set aside for the string variable. This number is called the maximum length of the string variable. At any time, the string variable may store any number of characters from 0 to its maximum length. The number of characters stored in a string at any particular time is called the current length. A string which contains no characters at all is called a null string. A null string has a length of zero. The system variable %B, which always contains the response given by the student at the last ACCEPT statement, is a string variable with a maximum length of 80 characters. It can be used in an expression or as the target of a COMPUTE. When the target is a string variable the expression is expected to yield a string value. If it happens to yield a numeric value, then PILOT automatically converts the numeric value to a string value by creating a string which represents what the numeric value would look like if printed out on the screen. It may seem odd to distinguish between a string value of "123.45" and a numeric value of 123.45; it is only within computers that such distinctions matter at all. PILOT frees you from being concerned with this distinction by automatically converting to the form needed to fit the context. The expression value is assigned to the string variable, replacing any previous value the string variable may have had. If the expression value is longer than the maximum length of the string variable, then the value is truncated (cut off on the right end) to the maximum length of the string variable. After the assignment, the current length of the string variable will be the number of characters actually assigned to the string variable. EXAMPLE 3: assignment to string variables D: DAY$(10) C: DAY$ = "TUESDAY" C: DAY$ = "Sun Oct 6, 1950" The last statement above results in variable DAY$ set to "Sun Oct 6," since its maximum length is 10. ASSIGNMENT TO A SUBSCRIPTED STRING A string variable can be thought of as storing a list of characters or bytes. It is possible to refer to a piece of a string, sometimes called a substring. To do so, place subscripts after the string variable name within parentheses. You can refer to one character within a string by placing one subscript after the string variable. The characters within a string are numbered from 1 (for the first character) to the current length of the string. To refer to several characters within a string, you place two subscripts in parentheses, separated by a comma. The first subscript denotes the starting position within the string, the second denotes the number of characters in the substring. If the second subscript is omitted, the length of the substring is 1. There are a few rules about what happens if you specify a target substring with a starting position and length which are out of the bounds of the current string length: (1) Since the first position of a string is position 1, if you specify a position less than 1, then PILOT assumes you mean position 1. (2) If you give a position greater than the current length of the string variable, then PILOT expands the string variable as necessary by adding blanks to the end of it. (3) If you give a position greater than the maximum length of the string, PILOT assumes you mean to position at the last character of the string. (4) If you specify a length which would go over the end of the string, the substring goes only to the end of the string. The result of an assignment to a substring is determined by several factors: the length of the expression value to be assigned, the current and maximum length of the string variable, and the values of the subscripts after the string variable name. To assign a value to a subscripted string variable the expression value is computed, if it is a number it will be converted to a string. Then, if the string value is longer than the substring to which it is being assigned, it is truncated (cut off from the right end) to the appropriate length. If the expression value is shorter than the substring to which it is being assigned, the value is padded on the right end to the appropriate length by appending spaces. EXAMPLE 4: assignment to substrings D: X$(10) (creates string X$) C: X$(10) = " " (sets X$ to 10 spaces) C: X$ = "ABCDEFGHIJ" (X$ now "ABCDEFGHIJ") C: X$(4) = "d" (X$ now "ABCdEFGHIJ") C: X$(3,5) = "xzy" (X$ now "ABxyz HIJ") C: X$(9,5) = "QRSTUV" (X$ now "ABxyz HQR") DIMENSION - allocate arrays and strings D: variable (size), . . . DX: variable (size), . . . DIMENSION creates an array of numbers or a character string. If the variable name ends with the "$" character a string is created, otherwise an array is created. Any number of arrays or strings can be created in one DIMENSION statement by separating each variable and size from the next by a comma. If an array or string has been created previously in the program, then an attempt to dimension the same variable again will first cause the previous contents of the array or string to be discarded. Then the new array or string is created as if for the first time. You should normally place all the DIMENSION statements for a program toward the beginning of the program, in such a place that they will be executed only once. DIMENSION OF A NUMERIC ARRAY An array is a list of numeric values. Each value can be accessed by the array name, followed by a subscript. A subscript is a numeric value in parentheses. The DIMENSION statement sets aside enough space to hold the specified size, plus one. The first item in an array is accessed by a subscript of 0, the next by a subscript of 1, and so on. The last item in an array is accessed by a subscript equal to the size value given on the DIMENSION statement. When an array is created via the DIMENSION statement, we sometimes say that the variable has been "dimensioned" to a particular size. When an array is created, the various numeric values in the array are not automatically initialized to any particular value. The initial value of any particular array item might be any number. DIMENSION OF A STRING VARIABLE If the variable name ends with a "$", then a string variable is created. A string variable stores a character string or a list of characters. The size given in the DIMENSION statement indicates the amount of memory set aside for the string variable and the maximum length character string that can be stored in the string variable. At any time the string variable can store any string up to the maximum string length. The number of characters stored in a string at any particular moment is called the current length of the string. An individual character position in a string variable can be accessed by a subscript. The first position of a string has subscript 1. When a string variable is created, it is initially set to a null string (i.e. a string with no characters in it). If you then wish to fill the string to its maximum length use a COMPUTE statement to assign a blank to the last character position. For example: D: XYZ$(3500) C: XYZ$(3500) = " " SPECIAL USES OF STRING VARIABLES There are several special purposes for string variables. One is to store a machine language subroutine to be called via the V: statement. If a string is to be used for this purpose, then you must append the X modifier to the D: op code when creating the string. This forces 16-byte memory alignment of the string start. This factor is only important for machine language programming due to the nature of the processor chip, and segment register limitations. The second special purpose for a character string is to hold a sprite table. A string to be used for this purpose must be created with a size of at least 2218 characters. A complete explanation of this feature is contained in the sprite section of this manual. ARRAY AND STRING SPACE CAPACITY PILOT sets aside approximately 35,000 bytes of space for storage of arrays and strings. The amount may be less if the computer memory is less than 256K bytes. Each array takes up 4 bytes per array item. Each string takes up one byte per string position. The same pool of space is used for scratch pad during various string manipulation operations, so if you get space error messages on a statement other than a dimension, you need to leave more space for scratch purposes. EXAMPLE 1: Create a numeric array with items numbered from 0 to 100. D: LIST(100) EXAMPLE 2: Create a string to store the student's name. D:NAME$(30) T:What is your name? A:$NAME$ EXAMPLE 3: Create a string to hold a machine language subroutine, and read the subroutine from disk into the string. DX: VEZ$(6000) FX:VEZ.BIN FI:0,VEZ$ EXAMPLE 4: Create a string to hold a sprite table, and read the sprite table from disk into the string. D:SPRI$(2218) FX:PLANETS.SPR FI:0,SPRI$ EXAMPLE 5: Create two string variables and three arrays in one statement. D: X$(20), Z$(340), A(100), B(200), C(3) See also: SUBSCRIPTING END - terminate subroutine or program E: E: destination The END statement has two purposes. First, if the use stack is empty, meaning that there is no un-ended USE in effect, then the END statement terminates the program and returns to DOS. Second, if the use stack is not empty, meaning that there is an un-ended USE statement in effect, the END statement pops the top entry off the use stack. This entry indicates the return point for the associated USE statement. The return point is the statement following the USE statement. If the END statement does not have a destination operand after the colon, then END jumps to the return point. If the END statement does have a destination after the colon then (after popping the entry off the use stack) END jumps to the label indicated on the END statement. This feature allows a subroutine called via the USE statement to return to either the statement after the USE or to another point in the program. This is particularly useful in conjunction with the ESCAPE command. The SYSX subroutine might be called from many places but might always exit to a menu or other common return point. See also: USE, GOTO AND ESCAPE EXAMPLE 1: END which always returns to DOS *QUIT E:QUIT EXAMPLE 2: END used to return from a subroutine *SUB T:Metric Conversion Table . . . E: FILE - access external or heap file FX: filename FX: FI: position-expression,variable$ FO: position-expression,value-expression FXH: heapsize FIH: position-expression,variable$ FOH: position-expression,value-expression The FILE statement provides access to disk files, the printer or auxiliary (RS-232 serial) port, a network or an in-memory file called the heap. To access a file, the program must first open the file. To open a file use the FX: statement. PILOT allows one open file at a time. Whenever you open a file, PILOT will close any previously opened file. The FX: statement without a filename after the colon, closes an open file without opening another file. Once a file is opened, the FI:, FILE IN statement, is used to read data from the file into a string variable. The FO:, FILE OUT statement, is used to write data from the program to the file.